Wiki Notes

Appearance

AI Agents 与工作流总目录 ​

版本：v1.11

最后更新：2026-07-09

这个目录现在作为 AI Agents专题 和 Agent与工作流 的统一入口使用。

它不是单纯把两个目录并排放在一起，而是把：

  • Agent 主线专题
  • 工作流与工程落地

两条线合成一张更接近真实工程的地图。

前者解决“什么情况下该用 Agent、怎么定义 specialist、怎样理解 tools / MCP / memory / protocols”；后者解决“状态机、补偿、恢复、审批、回放和人工纠偏怎么真的落地”。

1. 这个总目录主要解决什么 ​

很多 Agent 资料的问题不是“没有内容”，而是结构有偏差：

  • 只讲框架，不讲什么时候根本不该上 Agent
  • 只讲 Demo，不讲 run state、approval、trace 和恢复
  • 只讲规划，不讲工具契约、补偿和执行边界
  • 只讲多 Agent，不讲为什么要拆、拆到哪一层才合理

这套资料希望按更贴近真实系统的顺序建立认知：

  1. 先判断问题是否真的需要 Agent。
  2. 再理解 Agent 的控制循环和核心组件。
  3. 再理解工具、状态、记忆、上下文和协议互操作。
  4. 最后进入工作流编排、评测、安全、恢复、补偿和项目实战。

2. 推荐阅读顺序 ​

2.1 想先补 Agent 主线 ​

  1. 01-基础与边界.md
  2. 02-核心循环与核心组件.md
  3. 03-架构模式与技术选型.md
  4. 04-Tools、MCP与外部系统接入.md
  5. 05-状态、记忆与上下文工程.md
  6. 06-评测、可观测性与安全.md

2.2 想补工作流与工程落地 ​

  1. ../Agent与工作流/index.md
  2. ../Agent与工作流/工作流状态机专题.md
  3. ../Agent与工作流/审批与人机协同模式专题.md
  4. ../Agent与工作流/长任务恢复策略专题.md
  5. ../Agent与工作流/工具调用补偿机制专题.md

2.3 想直接看协议、接入层和互操作 ​

  1. 04-Tools、MCP与外部系统接入.md
  2. 10-AI协议生态与互操作.md
  3. ../Agent与工作流/工具权限沙箱专题.md

2.4 想把 MCP、Skill 和 Tool 分开看 ​

  1. 04A-Tool能力接口与执行边界.md
  2. 04B-MCP协议与连接器接入.md
  3. 04C-Skill任务封装与复用.md

这三页分别负责：

  • Tool：最小能力接口、参数与结果契约、执行与副作用边界
  • MCP：tools / resources / prompts、server / connector、认证与信任边界
  • Skill：instructions、context template、allowed tools、execution policy 与输出契约

2.5 想直接看带代码的 Claude 风格案例分析 ​

  1. 11-Claude式LLM与Agent案例分析.md
  2. 08-项目实战与作品集.md
  3. 09-Loop与Agent执行循环.md

这条阅读线更适合已经会调模型 API、现在想把下面三件事一起看清楚的同学：

  • 什么情况下先用 LLM 节点就够了
  • 什么情况下必须进入 Agent 工具循环
  • 怎么把 Claude 的 tool_use / tool_result / stop_reason 真的落成代码骨架

3. 最该先建立的几个共识 ​

3.1 不是所有复杂任务都需要多 Agent ​

OpenAI 当前 Agent definitions 和 Orchestration and handoffs 的官方资料，阅读顺序非常明确：

  • 先有一个 focused specialist
  • 复杂度上升后再进入 handoff、review、multi-step orchestration

这背后的工程含义是：

  • 多 Agent 应该是复杂度上升后的选择，而不是默认起手式

3.2 Agent 真正难的部分通常不在“说”，而在“做” ​

一旦系统开始接工具、连接器、MCP server、审批、人审和外部状态，问题就会从文本生成转成：

  • 执行
  • 权限
  • 恢复
  • 补偿
  • 观测
  • 治理

3.3 Agent 和工作流不是对立关系 ​

工作流负责把确定性部分收口，Agent 负责处理不确定性较高的判断和规划。把两者放在一个总目录里，更贴近真实系统里的混合模式。

3.4 什么时候该拆成多个 specialist，官方其实给了很明确的标准 ​

OpenAI 当前 Agent definitions 明确建议：

  • 先定义一个最小、职责清晰的 focused agent
  • 只有在 ownership、tool surface、approval policy、model / output style 明显不同的时候，再拆成多个 specialist

所以很多团队真正该问的不是“要不要多 Agent”，而是：

  • 它们是不是需要不同工具面
  • 它们是不是需要不同审批策略
  • 它们是不是需要不同模型和输出契约
  • 你是不是只是想在 trace 里显式看到路由，而不是逻辑上真的需要独立控制权

3.5 本地上下文和模型上下文不是一回事 ​

OpenAI 当前 Agent definitions 专门把 local context 和 model context 分开讲。

这意味着很多运行时数据不应该默认塞给模型，比如：

  • 已认证用户信息
  • 数据库连接
  • 内部 logger
  • 私有 helper function
  • 只给业务代码使用的状态对象

如果模型真的需要某个事实，就应该通过 instructions、input、retrieval 或 tool 明确给它；如果只是运行时依赖，就留在本地上下文里。

3.6 orchestration、approval 和 execution workspace 是三层不同控制面 ​

OpenAI 当前 Running agents、Guardrails and human review、Sandbox agents 其实把三层边界讲得很清楚：

  • orchestration：谁负责当前回合、谁调用谁、状态如何继续
  • approval / guardrail：哪些动作需要验证、阻断或人工确认
  • execution workspace：哪些任务需要文件系统、命令、脚本、端口和可恢复工作区

很多 Agent 系统做着做着会乱，往往不是模型不够强，而是把这三层混在一起了。

4. 如何使用这套资料 ​

如果你是：

  • 零基础 LLM 应用学习者 先看 01、02、04、07，再进入工作流专题。
  • 已经会调 API，想做 Agent 从 02 开始，然后看 03、04、05、06、10。
  • 准备做企业内部 Agent 重点看 03、04、05、06，并结合 Agent与工作流 里的状态机、审批、恢复和补偿专题。
  • 准备面试或整理知识库 从主线看完，再把工作流专题里的治理部分接进自己的答案体系。

5. 什么情况下不一定要上 Agent ​

很多问题其实更适合：

  • 直接做一个结构化输入输出的单轮工作流
  • 先用检索 + 模板 + 审批解决
  • 先把人机协同步骤显式建出来

如果一个流程的分支很少、输入输出很稳定、失败代价很高，那么先做工作流或规则系统，往往比一开始就上自由 Agent 更稳。

6. 怎样把 Agent 主线接到工程落地 ​

比较常见的顺序是：

  1. 先在主线专题里理解边界、循环、工具和状态。
  2. 再到 Agent与工作流 里补状态机、审批、恢复、补偿和观测。
  3. 最后再把平台工程、安全治理和评测运营接进来。

也就是说，Agent 真正难的部分不是“会不会规划”，而是“规划后的执行链路能不能被系统接住”。

7. Agent 系统里最容易漏掉的五类控制对象 ​

7.1 Agent 定义对象 ​

不管是 OpenAI 当前的 focused agent 定义，还是 Anthropic 当前 Managed Agents 的 versioned agent configuration，本质上都在强调一件事：

  • agent 本身是一个可复用、可版本化的能力对象

至少要明确：

  • 它的职责边界
  • 它允许使用哪些工具 / MCP / connectors
  • 它遵守什么审批和 guardrail 策略
  • 它是否有独立模型、输出契约和评测口径

7.2 工具契约对象 ​

很多系统把工具只当成“函数名 + 参数”，但真实工程里更关键的是：

  • 输入 schema
  • 输出 schema
  • 幂等性
  • 超时 / 重试策略
  • 副作用说明
  • 失败后的补偿与人工接管点

如果工具契约不清楚，Agent 再会规划也很难真正稳定执行。

7.3 run / session / memory 对象 ​

OpenAI 当前 Running agents 明确提醒：

  • 一个应用里最好给同一会话选定一种状态策略
  • 本地回放和服务端状态混用时，容易重复上下文
  • session 更适合 durable memory、可恢复审批流和应用可控存储

这意味着你至少要区分：

  • 单次 run
  • 多轮 session
  • 跨 session 的长期 memory

否则“记忆问题”很快会和“上下文重复”“回放不一致”“审批恢复失败”混在一起。

7.4 approval checkpoint 对象 ​

高风险 Agent 里，审批不是一个 UI 按钮，而是一类独立控制对象。通常至少要明确：

  • 哪些动作必须人工确认
  • 哪些工具结果需要二次校验
  • 驳回后 run 怎么继续、回滚还是改写计划
  • 谁对这次批准负责，审计证据落在哪里

如果没有这一层，所谓“人机协同”常常只是把风险甩给最后一个操作者。

7.5 trace / artifact / eval bundle 对象 ​

Agent 事故最怕的不是当时失败，而是事后只剩一句“它跑偏了”。

更稳的系统通常会把下面这些资产连起来：

  • trace
  • tool call records
  • 中间 artifacts
  • approval events
  • release bundle
  • 对应的 eval dataset / failure bucket

这样复盘时才能回答：

  • 它为什么这样规划
  • 它在哪个工具边界失败
  • 这次失败后来有没有进入回归集

8. 企业里最常见的七个 Agent 主线判断 ​

8.1 先做工作流，还是一开始就上 Agent ​

OpenAI 当前 Running agents、Orchestration and handoffs、Guardrails and human review 的主线都在说明：应该先把能确定的部分收进 workflow，再把不确定的决策留给 Agent。分支少、输入输出稳定、失败代价高的场景，通常先做工作流更稳。

8.2 单 Agent 够不够，还是要多 Agent ​

很多系统真正需要的只是一个 specialist agent 加几类工具，而不是多个 agent 互相转派。只有当职责边界、上下文、权限和评测都已经明显不同，多 Agent 或 handoff 才更有价值。

8.3 handoff 和 tools-as-agents 不是一回事 ​

handoff 更像把控制权交给另一个 specialist；tools-as-agents 更像把另一个能力封成受控子任务。两者的状态、追踪、责任边界和回退方式都不一样。

8.4 MCP、连接器和自定义工具不要混成一个概念 ​

OpenAI 当前已经把 MCP and Connectors 单独作为接外部世界的一层能力来讲。更务实的理解是：

  • 自定义工具：更适合单体场景的明确接口
  • MCP：更适合标准化暴露企业能力
  • connectors：更适合接已有外部系统和 SaaS

8.5 Agent 难点通常不在“规划”，而在“执行链路被系统接住” ​

很多项目卡住，不是因为 Agent 不会想，而是因为工具边界、状态恢复、审批、人审、回放和补偿都没有准备好。

8.6 会话状态到底该本地回放，还是交给 session / server-managed state ​

OpenAI 当前 Running agents 已经明确提醒：大多数应用里，最好给一个会话选定一种状态策略，不要一边本地 replay、一边再混 server-managed state，除非你明确在做两层 reconciliation。

这背后的判断通常是：

  • 想要完全可控和自建持久层，用本地 / 应用侧 session
  • 想要更直接的多轮持续状态，用 server-managed state
  • 想要 durable memory、可恢复审批流和应用可控存储，session 往往更合适

8.7 shell / 代码 / 文件工作区到底是偶发工具，还是独立执行层 ​

OpenAI 当前 Sandbox agents 的官方说明很直接：

  • 如果任务需要目录、文件、脚本、包依赖、产物、可恢复工作区和暴露端口，就不只是“多了一个 shell 工具”，而是进入了 sandbox / workspace 设计问题

9. 不同系统形态更适合先看什么 ​

9.1 单 Agent + 工具调用 ​

更适合先看：

  1. 02-核心循环与核心组件.md
  2. 04-Tools、MCP与外部系统接入.md
  3. 05-状态、记忆与上下文工程.md

9.2 workflow + Agent 混合系统 ​

更适合先看：

  1. 03-架构模式与技术选型.md
  2. ../Agent与工作流/index.md
  3. ../Agent与工作流/审批与人机协同模式专题.md

9.3 多 Agent / handoff 系统 ​

更适合先看：

  1. 03-架构模式与技术选型.md
  2. 04-Tools、MCP与外部系统接入.md
  3. 10-AI协议生态与互操作.md

9.4 高风险企业内部 Agent ​

更适合先看：

  1. 06-评测、可观测性与安全.md
  2. ../Agent与工作流/工具权限沙箱专题.md
  3. ../安全治理/index.md

9.5 长任务、异步和托管式 Agent 基础设施 ​

更适合先看：

  1. 03-架构模式与技术选型.md
  2. ../LLMOps专题/README.md
  3. ../Agent与工作流/长任务恢复策略专题.md

10. 什么时候该从这里切到别的目录 ​

10.1 开始怀疑其实是 LLM / RAG 基础没打牢 ​

切到 ../LLM专题/README.md 和 ../知识库与检索/index.md。

10.2 开始怀疑系统问题不在 Agent，而在发布、回滚、trace 和 runbook ​

切到 ../LLMOps专题/README.md 和 ../平台工程/index.md。

10.3 开始怀疑真正风险在权限、审批和人机接管 ​

切到 ../安全治理/index.md 和 ../AI安全专题/README.md。

10.4 开始怀疑核心问题是状态机、恢复和补偿 ​

切到 ../Agent与工作流/index.md。

11. 建议搭配阅读 ​

12. 重点官方资源 ​

以下资源已按 2026-07-08 核查可访问：